One or more of the following people are relevant to this code:

• @Qiskit/terra-core

This is borne out of an attempt to make "feature" mean "addition", in which case performance doesn't fit. We already do this with the GitHub-space changelog, and even the reno "features" section is called "New features". I feel like your suggestion is to treat "feature" as just meaning "improvement", but imo that's not a particularly useful distinction to readers - you could argue that a bug fix is an "improvement".

To me that would have been a features_qpy note that documented the speed up by rewriting it in Rust, including numbers, benchmarking scripts, etc.

Some of the point of this is that the port to Rust of QPY didn't add any new features (in theory), it just improved existing ones. (Also, somewhat beside the point, but I think benchmarking scripts are probably too much detail for being inline in a release note. Maybe a rough indicative number and a link to a comment in the relevant PR that has scripts/graphs would be a better split.)

I also wonder if we want some rigor in reporting numbers for this section. Besides the obvious question of what is the threshold for what we document in a release note (e.g. is 2% faster in a minority of cases warranted). They'll say something like "it's significantly faster now because of a port to Rust". If we want to have a dedicated section on this in release notes I'd think we want some standards about how we report it.

Personally I'd actually see the point of this section as going the complete other direction: release notes should let users know what changed in case of bugs / notify them of new things to try, so having a dedicated section for performance where we don't have to try to shoe-horn it into the "it's a new performance feature and here's the number to justify it" format will make it easier to have one-line informal notes about it, and I think we should do that fairly liberally on any patch that modified code with the intent of making it faster, not matter how much.

Release notes aren't the place to write full technical details about everything that changed and the situations that they apply to - imo they're the overview to let users know what changed, and include links to more detail if they want to follow up on the technicalities.

Like Jake I also think of "features" as functional changes and to this end a performance category seems distinct to me. If we continue with this thinking, would it help to stress the difference more explicitly, say in the features part in releasenotes/config.yaml?

Release notes aren't the place to write full technical details about everything that changed and the situations that they apply to - imo they're the overview to let users know what changed, and include links to more detail if they want to follow up on the technicalities.

The problem is that the details should exist somewhere, and in my experience they don't exist in most cases unless you require it somewhere. Or if they do how things are measured is inconsistent and not clear. You and I tend to put detailed performance numbers in PR comments or PR summaries (respectively) so it's easy to link to that, but that's far from universal. How many PRs are we going to document in this way where there are not any hard numbers backing it up and just an intent to speed it up? Even if it's me sharing a big table of asv results in a PR comment, that's really opaque to someone that's never seen our asv numbers and there is a lot of shared context assumed there.

I mean we both acknowledge disagreeing on the scope of release notes. In my mind it is the detailed documentation of the release. The release notes should cover everything user facing we included in the release. This is what differentiates the release notes from the changelog which is just a PR summary line and a link to the PR. I think it's where we should put all the details about what changed, why it changed, and how you use the changes. This isn't in lieu of having real documentation but we should have sufficient details in there so someone understands the changes made in the release. In my experience if you have to click through to multiple links that just makes it hard for people to find and doesn't have any consistency. Especially in this case if there is an evolution of performance in the development of the PR that's tracked through successive comments that github hides by default. But I'm fine not seeing eye to eye on that and trying it a different way. But if we are going to start calling out performance I want people to be able to understand why we're calling it out and what they can expect and I worry just saying something like "random circuit synthesis is faster now in some scenarios see: #123456667 for details" does not help with that understanding.

Like Jake I also think of "features" as functional changes and to this end a performance category seems distinct to me. If we continue with this thinking, would it help to stress the difference more explicitly, say in the features part in releasenotes/config.yaml?

If that is the intent of the move I think tweaking the template language to make it clear that "features" === "additions" or however you want to word it would help. Right now it doesn't define what a feature means and it's left to interpretation.

If that is the intent of the move I think tweaking the template language to make it clear that "features" === "additions" or however you want to word it would help. Right now it doesn't define what a feature means and it's left to interpretation.

How is this language as an addition on top of the features section in the release notes template file:

A feature is a new user-visible functionality. It can come in the form of a new function, class, parameter, environment variable or any other user accessible and publicly documented endpoint. In addition, new capabilities (for example "Qiskit can now compile to Clifford+T"), newly supported workflows and new types of language interoperability are considered features.

Jake, Matthew: I've added the additional explanation to the features section in the template file. Is there anything else you'd like to discuss or have addressed here?